v8.0.0

Compare Source

Nov 3, 2024

SUMMARY

Version 8.0.0 makes FlexColorScheme fully aligned with Flutter's MAJOR BREAKING Material-3 theming changes introduced in Flutter version 3.22. Due to Flutter 3.22 breaking many past Material styles, introducing new colors to ColorScheme and deprecating three colors, FlexColorScheme had to undergo major revision and also break many of its past styles and some older APIs.

Most APIs are still there and work as before, but a few produce results that differ slightly from past ones, just like Flutter 3.22 also does over previous versions. Generally, the upgrade should be smooth, but you may need to review the produced theme result to see that you don't get any changes that don't fit with your design goals. Some past defaults have changed in FCS V8, but previous settings are still available. However, you will need to enable them explicitly to get the same results as before. The purpose of these default value changes is to make FCS have less opinionated defaults, and be more aligned with Flutter's Material-3 design defaults. The Themes Playground app will still have some of its own opinionated defaults, done via default settings values the app uses in its default configuration, but the package Material-3 default starting points are now much more aligned with Flutter's Material-3 defaults.

In the Themes Playground you can now export and import settings to a JSON file, and import them back into the Playground later. This is a great way to save your theme settings for later re-use. The exported JSON contains all the internal controller settings values you have configured in the Playground app, that are needed to restore a given configuration state. This Playground feature was a nice contribution by GitHub user @​akiller in !PR 257, thank you! This contributed feature got enhanced with more error handling and a slightly refined UI to make it production ready. As a further enhancement of the JSON export feature, the Themes Playground app also got the ability to convert the exported settings JSON config to a shareable URL. You can now share Playground settings with other Flutter developers.

MIGRATION

The most critical changes to migrate from FlexColorScheme V7 to V8 are listed below. For a full list of all breaking changes, see PACKAGE CHANGES and the BREAKING part further below.

• The flag useMaterial3 now defaults to true in FlexColorScheme and FlexThemeData constructors. Set it to false to explicitly use Material-2 theming. It defaulted to true before. Material-2 is still fully supported in FCS v8 and Flutter v3.24, but will eventually be deprecated in Flutter, when that happens, it will also happen in FCS.

  With the Themes Playground app, you can use a pre-configured Material-3 based theme that looks very similar to legacy Material-2 design. This will continue to be available also after Material-2 is deprecated in Flutter.

• The FlexSubThemesData properties interactionEffects, tintedDisabledControls, defaultUseM2StyleDividerInM3 and blendOnColors now all default to false. In previous versions they defaulted to true. If you before had not explicitly turned these properties false, they were all true by default. To get the same result as before in FCS V8, you now have to set these properties to true. This change was made to have fewer opinionated defaults in FCS to align it more with Flutter SDK default styles.

• The FlexSubThemesData property navigationRailLabelType no default to NavigationRailLabelType.none. To get the same result as before by default, you will need to set it to NavigationRailLabelType.all. This change was made to have fewer opinionated defaults in FCS to align it more with Flutter SDK default styles. The Playground defaults it to NavigationRailLabelType.all by adding this by default to new default themes.

• Since ColorScheme.background color was deprecated in Flutter 3.22.0 we can no longer use it as a part of surface blends and its modes. For example, when surfaceMode is set to FlexSurfaceMode.highBackgroundLowScaffold it now uses surface and dialog blends set to 2x instead of 1x, so that it represents the "high background" style as before, but done via surface color. Without this breaking change, this mode would produce the same result as FlexSurfaceMode.levelSurfacesLowScaffold and be redundant.

  • NOTE: You may want to check your surface mode and blends to see that they still look as you want them to, as they may have changed slightly depending on your configuration. We have tried to keep required changes subtle, you may not notice any difference, but it is good to check. These changes we forced by Flutter 3.22.0 deprecation of ColorScheme colors background, onBackground and surfaceVariant.

This major release has many breaking changes forced via breaking changes in Flutter 3.22.0. Due to this, the release also uses this opportunity to clean up APIs with opinionated defaults, like the ones mentioned above. There are additional smaller and more subtle changes in defaults values, that align FCS to use the same color defaults from the new ColorScheme colors, that Flutter started using in version 3.22.0 as well. You can find all the details below in the PACKAGE CHANGES chapter.

BACKGROUND

Flutter 3.22 introduced a large number of breaking changes to the ColorScheme and default color mappings that Flutter's Material components use. In total, the Flutter 3.22.0 release adjusted 249 of its own internal tests to accommodate for new Material-3 spec changes, that all broke past Flutter Material-3 component styles. For a reference to the broken and updated tests, see this issue side comment.

FlexColorScheme V8 now allows you to use the new colors introduced in Flutter 3.22. As before, with FCS you can get fully defined hand-tuned ColorSchemes without using Material-3 design's Material Color Utilities (MCU) based seed-generated ColorSchemes. You may prefer to use seed generated ColorSchemes with Material-3, but it is nice to know you do not have to.

To the seed generated ColorSchemes, FCS adds support for all the Flutter DynamicSchemeVariant seed generated variants. It also improves them by allowing you to use separate seed colors for each palette. With Flutter's ColorScheme.fromSeed, you can only seed with one color, the primary color. The resulting ColorScheme always uses computed values for secondary and tertiary palettes, plus a hard coded fixed color for the error palette seeding. Surfaces colors are always tied to primary color as well and include a hint of primary color. With FCS, you do not have these limitations, you can seed with separate colors for each palette with even with Flutter's own dynamic scheme variants. This was always possible with FlexColorScheme and its FlexSeedScheme (FSS) based FlexTones, seed generated scheme variants. FCS now brings this feature to Flutter's own dynamic scheme variants as well.

As before, FCS also has its own even configurable FlexTones way of making seed generated ColorSchemes. Typically, you use predefined FlexTones, but you can also create your own FlexTones configurations. With it, you can define the chroma goals for each palette and define which tone is mapped to what ColorScheme color. An internal example of using them is the implementation of FlexTones modifiers.

FlexColorScheme V8 adds three new FlexTones modifiers. The most useful one is called monochromeSurfaces(). This tone modifier makes the surface shades of any used FlexTones configuration use monochrome greyscale shades for the surface and surface variant palettes. It thus gives us greyscale colors for ALL surfaces, instead of primary-tinted ones. It can be applied to any FlexTones seed generated scheme variant. The other new modifiers are expressiveOnContainer() and higherContrastFixed(). Check the API docs for more details.

PACKAGE CHANGES

This section contains a detailed list of all changes introduced in FlexColorScheme version 8.0.0.

BREAKING CHANGES

This version contains a lot of breaking changes due to updates in the Material-3 ColorScheme in Flutter 3.22. At the same time, this release uses the forced breaking change to clean up some older APIs. FCS is now more aligned with Flutter's Material-3 theming defaults, by typically using them as starting points in the default Material-3 mode. Material-2 mode is still supported, it has its own opinionated defaults as before.

• The ThemeData flag useMaterial3 is now true by default to align with Flutter 3.16.0 and later default for ThemeData. To continue using Material-2 theming, set useMaterial3 to false. All component themes in FlexSubThemes that have a useMaterial3 property now also default to true.

• Keeping to Material-3 defaults, in the theme factories light and dark, if scheme is undefined it now defaults to FlexScheme.materialBaseline the Material-3 baseline scheme, when useMaterial3 is true. If useMaterial3 is false and schemeis undefined, it defaults to FlexScheme.material, the default Material-2 theme, as before.

• Removed ALL references to in Flutter 3.22 deprecated ColorScheme colors background, onBackground and surfaceVariant. They are not used in FCS anymore. The background color was critical for FCS surface blending, it is now handled differently. The removal of these ColorScheme colors had far-reaching, but typically still subtle implications on styles created by FCS. There are many breaking minor style changes in this release due to this. Here are the critical changes caused by all these breaking changes in Flutter 3.22:

  • Deprecated background and onBackground colors in FlexColorScheme, FlexColorScheme.light, FlexColorScheme.dark, FlexThemeData.light and FlexThemeData.dark factories. They are not used anymore. Use surface and onSurface colors instead.
  • Deprecated background, onBackground, surfaceVariant from FlexSchemeOnColors and FlexSchemeSurfaceColors. They are no longer used and have no function. They were deprecated since the same colors were deprecated in ColorScheme in Flutter 3.22.
  • Deprecated surfaceVariantAlpha and backgroundAlpha colors in FlexAlphaValues. They are not used anymore and have no function, use surfaceAlpha instead. They were deprecated since the colors they related to were deprecated in ColorScheme in Flutter 3.22.
  • The FlexSchemeSurfaceColors.blend factory constructor produces slightly different blend result than in earlier versions. Because Flutter 3.22 deprecated ColorScheme colors background, onBackground and surfaceVariant, that were used in the blend calculation earlier. It is no longer possible to produce the same results as before, but the results are equivalent to previous design intent. With one exception, using surfaceMode with FlexSurfaceMode.highBackgroundLowScaffold sets surface and dialog blends to 2x instead of 1x, so that it represents the "high background" style as before, but done via surface. Without this breaking change, this mode would produce the same result FlexSurfaceMode.levelSurfacesLowScaffold and be redundant.
  • The enum SchemeColor removed all the corresponding colors that Flutter 3.22 deprecated. This is a VERY breaking change and will break your code if you happened to use any of the removed enum values. This may likely happen. The removed enum values are: SchemeColor.background, SchemeColor.onBackground and SchemeColor.surfaceVariant. For background Flutter recommends that you should use the values SchemeColor.surface and SchemeColor.onSurface instead and for surfaceVariant the SchemeColor.surfaceContainerHighest is recommended. In all cases you can try the other new surface colors as well, to see what best fits your design goals and intent.
  • The enum SchemeColor got support for all the new colors in Flutter 3.22 ColorScheme. It also removed the colors Flutter 3.22 deprecated. The order of the enum values was modified. This will break usage that depends on the enum's index, for example, storage of the values for implementations that depend on the index value.
  • Property systemNavBarStyle in FlexColorScheme.themedSystemNavigationBar now defaults to FlexSystemNavBarStyle.surface, instead of FlexSystemNavBarStyle.background. Using FlexSystemNavBarStyle.background results in the color Theme.of(context).colorScheme.surfaceContainerLow being used, where it previously was Theme.of(context).colorScheme.background. This is because Flutter 3.22 deprecated ColorSCheme.background.
  • The enum FlexAppBarStyle value background now results in the AppBar using the surfaceContainerLow color instead of background. This breaking change was introduced because of the breaking change in Material-3 in Flutter 3.22 where the color background was deprecated. The new color is kind of the best match for the old background color in a typical FCS configuration.
  • The enum FlexSystemNavBarStyle value background now results in the app bar using the surfaceContainerLow color instead of background. This breaking change was introduced because of the breaking change in Material-3 in Flutter 3.22 where the color background was deprecated. The new color is kind of the best match for the old background color in typical FCS configuration.

• Breaking rename: All helper component themes in FlexSubThemes ended with Theme, as designed, except FlexSubThemes.bottomNavigationBar. This mistake is now corrected, it was renamed to FlexSubThemes.bottomNavigationBarTheme. The old version is deprecated and passes its props through to the renamed version. The old and wrong named one will be removed in version 9.0.0.

• Deprecated FlexSubThemesData.blendTextTheme, it no longer has any function. See topic "Why is blendTextTheme deprecated?" further below for more information,

• Deprecated the FCS legacy property useFlutterDefaults. FlexColorScheme in Material-3 mode now defaults to using Flutter default styles. For other configurations, modify them as desired. In Material-2 mode, FCS continues to use its opinionated own defaults as before, as long as Material-2 exists.

• Deprecated the static function FlexColorScheme.createPrimarySwatch, it is no longer used by FlexColorScheme internally, it is now deprecated in FlexColorScheme and will go away in V9. After this, you will still be able to find this function in ColorTools in the package flex_Color_picker, where it will remain available.

• Replaced the FCS legacy property useTextTheme with a more feature correctly named property useMaterial3Typography. Use it instead. The useTextTheme originally had another function in much older versions of FCS. Its name no longer represented its function, the new name does. If not defined, the default is true in Material-3 mode and false in Material-2 mode. If you still use Material-2, try setting this to true to get nicer typography in Material-2 mode.

• The color material3DarkOnErrorContainer was changed from Color(0xFFFFB4AB) to Color(0xFFFFDAD6) to match the new Material-3 default dark error color used in Flutter 3.22.

• Dialog background color now defaults to surfaceContainerHigh with no elevation tint color in Material-3 mode, instead of surface with elevation tint. Breaking change introduced to match the breaking change in Material-3 defaults in Flutter 3.22.

• The ElevatedButton background color now defaults to surfaceContainerLow with no elevation tint color in Material-3 mode, instead of surface with elevation tint. This breaking change was introduced to match the breaking change in Material-3 defaults in Flutter 3.22.

• The PopupMenuButton background color now defaults to surfaceContainer with no elevation tint color in Material-3 mode, instead of surface with elevation tint. This breaking change was introduced to match the breaking change in Material-3 defaults in Flutter 3.22.

• The MenuBar background color now defaults to surfaceContainer instead of surface with elevation tint in Material-3 mode. This breaking change was introduced to match the breaking change in Material-3 defaults in Flutter 3.22.

• The produced MenuTheme background color now defaults to surfaceContainer with no elevation tint color in Material-3 mode, instead of surface with elevation tint. This breaking change was introduced to match the breaking change in Material-3 defaults in Flutter 3.22. This affects default background color of the opened menu on MenuBar, MenuAnchor and DropdownMenu.

• The BottomSheet background color now defaults to surfaceContainerLow with no elevation tint color in Material-3 mode, instead of surface with elevation tint. This breaking change was introduced to match the breaking change in Material-3 defaults in Flutter 3.22.

• The produced DrawerTheme background color now defaults to surfaceContainerLow with no elevation tint color in Material-3 mode, instead of surface with elevation tint. This breaking change was introduced to match the breaking change in Material-3 defaults in Flutter 3.22. This affects the default background color of the Drawer and NavigationDrawer. FCS uses surfaceContainerLow as background color in Material-2 mode by default too.

• The produced DrawerTheme width now defaults to 304 dp in Material-3 mode. The [official Material-3 spec is 360 dp](Material-3 spec https://m3.material.io/components/navigation-drawer/specs), FCS was using it, but Flutter SDK has so far "declined" following the Material-3 spec here and still uses the older default 304 dp used in the Material-2 spec. This older default is actually a better choice, so FCS has now opted to revert to using it as default too. For more information about this and why 304 dp is better, see Flutter issue #​123380.

• The FlexSubThemesData properties interactionEffects, tintedDisabledControls and defaultUseM2StyleDividerInM3 now all default to false. In previous versions they defaulted to true. This change was made to have fewer opinionated defaults in FCS to align it more with Flutter SDK default styles. If you had NOT configured these values before, they defaulted to true. You now have to set them explicitly to true to opt in and get the same results as you got before when they were not configured.

• The FlexSubThemesData properties blendOnColors now defaults to false. In previous versions it defaulted to true. This change was made to have fewer opinionated defaults in FCS, to align it more with Flutter defaults. If you had NOT configured this values before, it defaulted to true. You now have to set it explicitly to true to get the same result as before, when it was not configured. Consider setting this property true in dark mode, and false in light theme mode, for a style that matches the Material-3 color design, when you are not using a seed generated ColorScheme. This setting has no effect when using a seed generated ColorScheme, as it generates blended/tinted onColors based on the seed algorithm, that overrides the effect of this setting. This setting creates a similar effect for none seeded ColorSchemes.

• The FlexSubThemesData property inputSelectionHandleSchemeColor when not defined, defaults to inputDecoratorSchemeColor and if it is not defined either, the effective text selection handle color result is ColorScheme.primary, same as Flutter SDK default. In previous versions, no definitions, resulted in ThemeData.primaryColorDark being used. This was changed in preparation of Flutter's planned deprecation of primaryColorDark.

• The FlexSubThemesData property inputDecoratorIsFilled now default to false when undefined, like Flutter SDK does. Set it to true to get the same style it had with previous undefined value.

• The FlexSubThemesData property inputDecoratorBorderType now default to FlexInputBorderType.underline when undefined, producing same default as Flutter SDK does. Set it to FlexInputBorderType.outline to get the same style it had with previous undefined value.

• The FlexSubThemesData property inputDecoratorUnfocusedBorderIsColored now default to false when undefined, like Flutter SDK does. Set it to true to get the same style it had with previous undefined value.

• In FlexSubTheme.InputDecorationTheme the following properties have new breaking default values: filled default to false, borderType default to FlexInputBorderType.underline and unfocusedBorderIsColored to false.

• The FlexSubThemesData properties navigationRailMutedUnselectedLabel and navigationRailMutedUnselectedIcon now default to false. In previous versions they defaulted to true. This change was made to have fewer opinionated defaults in FCS and follow Material-3 design spec by default.

• The FlexSubThemesData properties navigationRailUseIndicator now defaults to null, resulting in true being used in Material-3 mode and false in Material-2 mode. In previous versions it defaulted to true. This change was made to have fewer opinionated defaults in FCS and follow Material design specs for default values. If you still use Material-2, you now have to set this to true to see the indicator. The Playground now always sets either true or false in both modes, it never leaves out the default choice in generated config code. The field is nullable, and you can now also get the M2/M3 different default styles, by not defining this property at all.

• In FlexSubThemes.navigationRailTheme the properties mutedUnselectedLabel and mutedUnselectedIcon now default to false if undefined. In previous versions they defaulted to true. Property selectedLabelSchemeColor defaults to onSurface and unselectedLabelSchemeColor default to onSurfaceVariant, they were primary before. Property unselectedIconColor now defaults to onSurfaceVariant it was onSurface. Property selectedIconColor now defaults to onSecondaryContainer it was primary. Property labelType now defaults to NavigationRailLabelType.none it was NavigationRailLabelType.all.

  • All these changes were made to have fewer opinionated defaults in FCS and follow Material-3 design spec by default. Past FCS defaults were made before some Material-3 specs existed. In some cases, earlier FCS versions also kept its opinionated defaults from Material-2 as defaults for its Material-3 default theme.

• The FlexSubThemesData properties navigationRailUnselectedLabelSchemeColor and navigationRailUnselectedIconSchemeColor now default to onSurfaceVariant (was onSurface). The onSurfaceVariant is used as on color pair default when any surface color is used as background color for the rail, if a none surface color is used as background scheme color, its contrast color pair is used as default for the labels and unselected icons. The navigationRailSelectedIconSchemeColor will if undefined, default to the contrast color pair for navigationRailIndicatorSchemeColor. These default behaviors result in less configuration in typical designs, while starting points defaults are the same as before and full configuration options are also available as before. The equivalent colors in FlexSubThemes.navigationRailTheme behave the same way.

• The FlexSubThemesData properties navigationBarMutedUnselectedLabel and navigationBarMutedUnselectedIcon now default to false. In previous versions they defaulted to true. This change was made to have fewer opinionated defaults in FCS and follow Material-3 design spec by default.

• In FlexSubThemes.navigationBarTheme the properties mutedUnselectedLabel and mutedUnselectedIcon now default to false if undefined. In previous versions they defaulted to true. Property selectedLabelSchemeColor defaults to onSurface and unselectedLabelSchemeColor default to onSurfaceVariant, they were primary before. Property unselectedIconColor now defaults to onSurfaceVariant it was onSurface. Property selectedIconColor now defaults to onSecondaryContainer it was primary.

  • All these changes were made to have fewer opinionated defaults in FCS and follow Material-3 design spec by default. Past FCS defaults were made before some Material-3 specs existed. In some cases, earlier FCS versions also kept its opinionated defaults from Material-2 as defaults for its Material-3 default theme.

• The FlexSubThemesData properties navigationBarUnselectedLabelSchemeColor and navigationBarUnselectedIconSchemeColor now default to onSurfaceVariant (was onSurface). The onSurfaceVariant is used as on color pair default when any surface color is used as background color for the rail, if a none surface color is used as background scheme color, its contrast color pair is used as default for the labels and unselected icons. The navigationBarSelectedIconSchemeColor will if undefined, default to the contrast color pair for navigationBarIndicatorSchemeColor. These default behaviors result in less configuration in typical designs, while starting points defaults are the same as before and full configuration options are also available as before. The equivalent colors in FlexSubThemes.navigationBarTheme behave the same way.

• The FlexSubThemesData properties bottomNavigationBarMutedUnselectedLabel and bottomNavigationBarMutedUnselectedIcon now default to null, resulting in true being used as default in Material-2 mode and false in Material-3 mode. In previous versions these properties defaulted to true in both modes. This change was made to have fewer opinionated defaults in FCS.

• The FlexSubThemesData properties bottomNavigationBarUnselectedLabelSchemeColor and bottomNavigationBarUnselectedIconSchemeColor now default to onSurfaceVariant in Material-3 mode, it was onSurface, which remains the default in Material-3 mode. In Material-3 mode, the onSurfaceVariant is used as on color pair default when any surface color is used as background color for the navigation bar. If a none surface color is used as background scheme color, its contrast color pair is used as default for the labels and unselected icons, in both Material-2 and Material-3 mode. These default behaviors result in less configuration in typical designs, while starting points defaults are the same as before and full configuration options are also available as before. The equivalent colors in FlexSubThemes.bottomNavigationBar behave the same way.

• The FlexSubThemesData property chipDeleteIconSchemeColor now default to SchemeColor.onSurfaceVariant. In previous versions it defaulted to SchemeColor.onSurface. Likewise in FlexSubThemes.chipTheme the property deleteIconSchemeColor now defaults to SchemeColor.onSurfaceVariant if undefined. In previous versions it defaulted to SchemeColor.onSurface. This change was made to adjust to follow updated Material-3 spec defaults.

• The FlexSubThemesData property drawerUnselectedItemSchemeColor now default to SchemeColor.onSurfaceVariant, as on color pair default when any surface color is used as drawer background color. Previously it defaulted to onSurface. Likewise in FlexSubThemes.navigationDrawerTheme the property unselectedItemSchemeColor now defaults to SchemeColor.onSurfaceVariant if undefined. This was changed to use ase as Material-3 defaults.

• Minor style breaking, the tinted interactions were slightly modified. They are now a bit less pronounced and also have a bit less gray in them.

NEW

• Added three new FlexSchemes, called blackWhite, greys and sepia. They are primarily intended to be used as prototype phase color schemes that do not use colors. This can be useful for focusing on features and layout during the early development phase, keeping the discussion away from colors. The schemes can also be used as neutral baselines for custom color schemes, where only a few colors are overridden with custom colors.

• The const color definition class FlexColor got 24 new color values to support monochrome greyscale colors for all new surfaces and their on colors for light and dark mode. These are used as starting colors for the new surface colors in the Flutter 3.22 updated and new Material-3 ColorScheme, when a seed generated ColorScheme is NOT used. These colors follow the naming convention lightFlexSurface___ and darkFlexSurface___, plus their on and inverse versions.

• Added named bool parameter useOnSurfaceVariant that defaults to false, to FlexSubTheme.schemeColorPair() and to FlexSubTheme.onSchemeColor(), when set to true, the on color onSurfaceVariant is returned instead for onSurface for all surface colors.

• Added black, white and transparent as enum values to SchemeColor. These are not ColorScheme colors, but these colors can in many theming situations be useful instead of the ColorScheme based ones.

  • The automatic on color pair for black is white and white for black. For transparent, it is onSurface.

• Added all the new surface colors in Flutter 3.22 to FlexSchemeSurfaceColors.

• Added all the new on colors in Flutter 3.22 to FlexSchemeOnColors.

• The FlexKeyColor class got three new properties, contrastLevel, useExpressiveOnContainerColors and useLegacyMonochromeSeedBehavior. They are used to control seed generation results.

  1. The contrastLevel is used to control the contrast level of MCU generated scheme colors. The contrastLevel parameter indicates the contrast level between color pairs, such as primary and onPrimary. The value 0.0 is the default, standard contrast; -1.0 is the lowest; 1.0 is the highest. From the Material-3 Design guideline, the standard, medium and high contrast options correspond to values 0.0, 0.5 and 1.0 respectively.

     • The contrastLevel property is only available when seed generating a ColorScheme using FlexSeedScheme's SeedColorScheme.fromSeeds when a scheme variant is used where its FlexSchemeVariant.value, isFlutterScheme is true. This set corresponds to all the DynamicSchemeVariants available in the Flutter SDK.
     • The contrastLevel is the same as the Flutter contrastLevel property available in ColorScheme.fromSeed. As of Sep 3, 2024, this contrastLevel is still only available in the master channel. It will land in the next Flutter stable, released after Flutter 3.24. With FCS v8 you can use it already now.

       When using FSS tones based seed generated schemes or a variant having its FlexSchemeVariant.value, isFlutterScheme it set to false, the contrastLevel value is ignored. With tones based schemes, the contrast level can instead be defined as desired using custom FlexTones configurations. There are two predefined higher contrast level tone and chroma mappings available as FlexTones.highContrast and FlexTones.ultraContrast, you can use them as they are, or as examples of how to create your own custom high contrast tone mappings.

  2. The boolean useExpressiveOnContainerColors is used to make the light theme mode colors onPrimaryContainer, onSecondaryContainer, onTertiaryContainer and onErrorContainer more color expressive, at the cost of their contrast level and accessibility. Defaults to false if undefined.

     • The Material design spec for the tones used by the colors onPrimaryContainer, onSecondaryContainer, onTertiaryContainer and onErrorContainer have changed from tone 10 to 30 for LIGHT theme mode. This change will land in Flutter when the Material Color Utilities (MCU) package is updated to at least 0.12.0. This has not been done even in master (Sep 3, 2024).
     • Setting the useExpressiveOnContainerColors to true will make the colors use the new expressive tone. The expressive tone spec is not yet used in Flutter SDK, but is in the Material-3 design spec and also in MCU v 0.12.0. When this change lands in stable Flutter, it will be made ON by default in FCS too. You will still be able to opt out of using it. Flutter SDK and MCU will not contain such an opt-out feature.
     • The new on color tones for containers in light mode make them more color expressive, but they also reduce their contrast level and accessibility. We recommend keeping them at the higher contrast level, by setting useExpressiveOnContainerColors to false. With it set to false, you will also keep this preference when the Flutter SDK defaults to using the expressive tones.

  3. The boolean useLegacyMonochromeSeedBehavior is used for enabling the legacy behavior for monochrome seed colors

     • With Flutter SDK and also FCS versions before 8.0.0, using a monochrome seed color or white color, resulted in a tonal palette with cyan color tones. Whereas a black seed color resulted in red like color tones. This is not very intuitive and not really expected or desired when using monochrome seed colors. In version 8.0.0 and later of FCS any monochrome RGB input value will result in the creation of a greyscale tonal palette for the palette using the monochrome seed color. An RGB monochrome value is one where Red, Green and Blue values are all equal.
     • If you require the old style seed result for monochrome seed colors, set useLegacyMonochromeSeedBehavior to true.
     • Defaults to false.
     • Under the hood this setting is passed to respectMonochromeSeed in SeedColorScheme.fromSeeds in FlexSeedScheme's internal MCU fork, and sets it !useLegacyMonochromeSeedBehavior. In FSS this feature is opt-in and recommended to be used. Here, in FCS this setting is opt-out if not desired, and it is strongly recommended to use the new behavior. When using useLegacyMonochromeSeedBehavior with

       When using useLegacyMonochromeSeedBehavior with DynamicSchemeVariant variants fidelity or content, for some monochrome input colors they produce primaryContainer and onPrimaryContainer as well as tertiaryContainer and onTertiaryContainer color pairs, with low contrast. Consider using some other scheme variants with monochrome seed colors. All others work well with any monochrome seed color. This is just how the MCU DynamicSchemes SchemeContent and SchemeFidelity are defined in MCU. They also produce fairly low contrast for these color pairs with very dark seed colors. This behavior with MCU's SchemeContent and SchemeFidelity could be fixed in FlexSeedScheme's internal MCU fork, but we want to keep the result of these schemes consistent with MCU.

• Added TextStyles for FlexSubThemesData so that:

  • FlexSubThemes.appBarTheme uses FlexSubThemesData.appBarToolbarTextStyle for its toolbarTextStyle.
  • FlexSubThemes.appBarTheme uses FlexSubThemesData.appBarTitleTextStyle for its titleTextStyle.
  • FlexSubThemes.chipTheme uses FlexSubThemesData.chipLabelStyle for its labelStyle.
  • FlexSubThemes.chipTheme uses FlexSubThemesData.chipSecondaryLabelStyle for its secondaryLabelStyle.
  • FlexSubThemes.datePickerTheme uses FlexSubThemesData.datePickerHeaderHeadlineStyle for its headerHeadlineStyle.
  • FlexSubThemes.datePickerTheme uses FlexSubThemesData.datePickerHeaderHelpStyle for its headerHelpStyle.
  • FlexSubThemes.datePickerTheme uses FlexSubThemesData.datePickerWeekdayStyle for its weekdayStyle.
  • FlexSubThemes.datePickerTheme uses FlexSubThemesData.datePickerDayStyle for its dayStyle.
  • FlexSubThemes.datePickerTheme uses FlexSubThemesData.datePickerYearStyle for its yearStyle.
  • FlexSubThemes.datePickerTheme uses FlexSubThemesData.datePickerRangePickerHeaderHeadlineStyle for its rangePickerHeaderHeadlineStyle.
  • FlexSubThemes.datePickerTheme uses FlexSubThemesData.datePickerRangePickerHeaderHelpStyle for its rangePickerHeaderHelpStyle.
  • FlexSubThemes.dialogTheme uses FlexSubThemesData.dialogTitleTextStyle for its titleTextStyle.
  • FlexSubThemes.dialogTheme uses FlexSubThemesData.dialogContentTextStyle for its contentTextStyle.
  • FlexSubThemes.floatingActionButtonTheme uses FlexSubThemesData.fabExtendedTextStyle for its extendedTextStyle.
  • FlexSubThemes.menuButtonTheme uses FlexSubThemesData.menuButtonTextStyle for its textStyle.
  • FlexSubThemes.timePickerTheme uses FlexSubThemesData.timePickerDayPeriodTextStyle for its dayPeriodTextStyle.
  • FlexSubThemes.timePickerTheme uses FlexSubThemesData.timePickerDialTextStyle for its dialTextStyle.,
  • FlexSubThemes.timePickerTheme uses FlexSubThemesData.timePickerHelpTextStyle for its helpTextStyle.,
  • FlexSubThemes.timePickerTheme uses FlexSubThemesData.timePickerHourMinuteTextStyle for its hourMinuteTextStyle.,
  • FlexSubThemes.toggleButtonsTheme uses FlexSubThemesData.toggleButtonsTextStyle for its textStyle.
  • FlexSubThemes.segmentedButtonTheme uses FlexSubThemesData.segmentedButtonTextStyle for its textStyle.
  • FlexSubThemes.snackBarTheme uses FlexSubThemesData.snackBarContentTextStyle for its contentTextStyle.
  • These are not available in the Themes Playground. Their purpose is that you can use them with the API to provide custom text styles for FCS styled components. You could do this in the past too, but you had to use rather complicated deep copyWith on the produced component themes. With these props you get access to direct TextStyle styling for these component properties in the FCS API too.

• Added useCupertinoStyle property to FlexSubThemes.switchTheme. Added switchAdaptiveCupertinoLike property to FlexSubThemesData and made FlexSubThemes.switchTheme use it.

• Added secondarySelectedSchemeColor, fontSize, secondaryFontSize, iconSize and padding properties to FlexSubThemes.chipTheme. Added chipSecondarySelectedSchemeColor, chipFontSize, chipSecondaryFontSize, chipIconSize and chipPadding properties to FlexSubThemesData and made FlexSubThemes.chipTheme use them.

• Added headerForegroundSchemeColor property to FlexSubThemes.datePickerTheme. Added datePickerHeaderForegroundSchemeColor property to FlexSubThemesData and made FlexSubThemes.datePickerTheme use it for its header foreground color.

• Added dividerSchemeColor property to FlexSubThemes.datePickerTheme. Added datePickerDividerSchemeColor property to FlexSubThemesData and made FlexSubThemes.datePickerTheme use it for its divider color.

• Added isDense property to FlexSubThemes.inputDecoratorTheme. Added inputDecoratorIsDense property to FlexSubThemesData.

• Added contentPadding property to FlexSubThemes.inputDecoratorTheme. Added inputDecoratorContentPadding property to FlexSubThemesData and made FlexSubThemes.inputDecoratorTheme use it.

• Added inputDecoratorSuffixIconSchemeColor property to FlexSubThemes.inputDecorationTheme. Added toggleButtonsSelectedForegroundSchemeColor property to FlexSubThemesData and made FlexSubThemes.segmentedButtonTheme use it.

• Added adaptiveInputDecoratorRadius and inputDecoratorRadiusAdaptive properties to FlexSubThemesData. They are used to select platform(s) to an alternative border radius response for the input decorator, for the selected platform(s).

• Added minWidth and minExtendedWidth to FlexSubThemes.navigationRailTheme. Added navigationRailMinWidth and navigationRailMinExtendedWidth properties to FlexSubThemesData and made FlexSubThemes.navigationRailTheme use them.

• Added tabAlignment property to FlexSubThemes.tabAlignment. Added tabBarTabAlignment property to FlexSubThemesData and made FlexSubThemes.tabBarTheme use it for its. (TODO: Add a note about thrown assert, open an issue in Flutter SDK about it and suggest an alternative solution.)

• Added foregroundSchemeColor property to FlexSubThemes.floatingActionButtonTheme. Added fabForegroundSchemeColor property to FlexSubThemesData and made FlexSubThemes.floatingActionButtonTheme use it for its foreground color.

• Added selectedForegroundSchemeColor property to FlexSubThemes.segmentedButtonTheme.

• Added segmentedButtonSelectedForegroundSchemeColor property to FlexSubThemesData and made FlexSubThemes.segmentedButtonTheme use it.

• Added selectedForegroundSchemeColor property to FlexSubThemes.toggleButtonsTheme.

• Added toggleButtonsSelectedForegroundSchemeColor property to FlexSubThemesData and made FlexSubThemes.toggleButtonsTheme use it.

• Added appBarForegroundSchemeColor, appBarIconSchemeColor and appBarActionsIconSchemeColor properties to FlexSubThemesData and made FlexSubThemes.appBarTheme use it for its colors on title, icon and actions.

• Added bottomAppBarHeight property to FlexSubThemesData and made FlexSubThemes.bottomAppBarTheme use it as its height value.

• Added scaffoldBackgroundBaseColor property to FlexSubThemesData. It is a FlexScaffoldBaseColor enum that can be used to select the base color used as Themedata.scaffoldBackgroundColor in a theme. The selected base color is modified by used surfaceMode and blendLevel] in the FlexColorScheme's light and dark factory constructors.

• Added scaffoldBackgroundSchemeColor property to FlexSubThemesData and made ThemeData.scaffoldBackgroundColor use it as an override color, if it is defined. Setting scaffoldBackgroundSchemeColor will override any blended background or true black or plain white setting.

• Added cupertinoOverrideTheme to FlexColorScheme constructor and to FlexColorScheme.light, FlexColorScheme.dark, FlexThemeData.light and FlexThemeData.dark factory constructors.

• Added enum variant a FlexSchemeVariant to FlexColorsScheme and FlexThemeData light and dark. This is used to define the variant of the seeded ColorScheme. It is an alternative to tones that also includes scheme seed variants that Flutter SDK added in version 3.22.2.

• Added enhanced enum functions data and colors to the FlexScheme enum, that returns the predefined FlexSchemeData and FlexSchemeColor respectively, that are associated with a given enum value. This could be done already using the FlexColor.schemes map. This is a convenience API to be able to use e.g. FlexColor.mango.data to get the predefined FlexSchemeData for the mango enum scheme and e.g. FlexColor.barossa.colors(Brightness.dark) to get the pre-defined dark colors used for the barossa scheme colors. See feature request: https://github.com/rydmike/flex_color_scheme/issues/210

• Added ability to use custom seed key colors to FlexKeyColors.

• Added support for error colors to FlexKeyColors.

• Added direct color properties for errorContainer and onErrorContainer to FlexColorScheme, FlexColorScheme.light, FlexColorScheme.dark, FlexThemeData.light, FlexThemeData.dark. It was required to support custom error container colors in the FlexKeyColors API.

• Added Color properties primaryLightRef, secondaryLightRef and tertiaryLightRef to FlexSchemeColor.

  • They are used to store references to the corresponding color in a FlexSchemeColor made for light mode in the dark mode FlexSchemeColor. This is used to create computed "fixed" and "fixedDim" colors for dark mode and the light mode ColorScheme that are identical in light and dark mode.
  • Made FlexSchemeColor(), FlexSchemeColor.from(), FlexSchemeColor.effective() and FlexSchemeColor.toDark() work correctly with the new primaryLightRef, secondaryLightRef and tertiaryLightRef properties.
  • Used all main light color properties in FlexSchemeData static FlexSchemeColor color definitions, as lightRef colors in their dark mode equivalent FlexSchemeColor. That was 156 color values to add to the 52 dark FlexSchemeColor definitions.

• Added fixedColorStyle to FlexColorScheme, FlexColorScheme.light, FlexColorScheme.dark, FlexThemeData.light, FlexThemeData.dark. It was required to support custom error container colors in the FlexKeyColors API. The property is an enum FlexFixedColorStyle, that allows us to choose the style of the generated "fixed" and "fixedDim" colors when not using seed generated color schemes.

• Added Color properties primaryLightRef, secondaryLightRef and tertiaryLightRef to FlexColorScheme.dark and FlexThemeData.dark. If you use the override colors primary, secondary or tertiary and are not using seeded ColorScheme, you need them to provide the correct light mode reference colors for computing fixed colors that will match the light mode fixed colors, for that it is required to know what the light mode colors are. If you are seeding and use the overrides, and will switch between seeded and not seeded, you can provide the override for the not seeded values in primary, secondary or tertiary, and the ref to their seed colors from light mode, in the light ref colors. If you always seed when using the overrides, you can also provide the seed colors in the primary, secondary or tertiary overrides, the light refs fall through to these colors in that cases if not provided during seeding.

• Added style navigationBar to enum FlexSystemNavBarStyle that use the color for default or themed NavigationBar background color on the system navigation bar helper.

  • You can get a similar result with the transparent option. Using the navigationBar option does not require using the edge-to-edge config required when using transparent system navigation bar to see things behind it. The transparent option sets edge-to-edge mode behind the scenes when used. This can cause some layout changes that must be considered in the app design when used. This is an optional way to style the system navigation bar to match the app's themed NavigationBar background color, without using edge-to-edge Android screen mode.

• Added ListTile theming support to FlexSubThemesData and made corresponding FlexSubThemes.listTileTheme properties use them in FlexColorScheme as ListTileTheme theming properties.

  • The following FlexSubThemesData properties were added: listTileSelectedSchemeColor, listTileIconSchemeColor, listTileTextSchemeColor, listTileTitleTextStyle, listTileSubtitleTextStyle, listTileLeadingAndTrailingTextStyle, listTileTileSchemeColor, listTileSelectedTileSchemeColor, listTileContentPadding, listTileHorizontalTitleGap, listTileMinVerticalPadding, listTileStyle, listTileTitleAlignment and listTileControlAffinity.

• Added SearchBar and SearchView theming support to FlexSubThemesData and made corresponding FlexSubThemes.searchBarTheme and FlexSubThemes.searchViewTheme properties use them in FlexColorScheme as SearchBarThemeData and SearchViewThemeData theming properties.

  • The following FlexSubThemesData properties were added: searchBarBackgroundSchemeColor, searchViewBackgroundSchemeColor, searchBarElevation, searchViewElevation, searchBarRadius, searchViewRadius, searchViewHeaderHeight, searchBarTextStyle, searchViewHeaderTextStyle, searchBarHintStyle, searchViewHeaderHintStyle, searchViewDividerColor, searchBarShadowColor, searchBarTextCapitalization, searchBarPadding, searchBarConstraints, searchViewConstraints and searchUseGlobalShape.

CHANGE

• Changed all internal usage of MaterialStateProperty and MaterialState to use new WidgetStateProperty and WidgetState introduced in Flutter 3.22 and later.

• Static functions FlexSubThemes.schemeColor and FlexSubThemes.onSchemeColor now support the updated SchemeColor and ColorScheme.

• Improved the theming logic for Card theme.

  • It now avoids issue #​153912, but only when the Flutter default radius is used. This is done by not creating a shape theme when the default radius is used and using the default created one instead. This will keep the outline for the default radius theme cases. Previously FCS Card theme created a shape with the default radius. Both cases are now using default and null radius value, it keeps shape null and lets the widget default behavior be used, so we can keep the outline on Card.outlined variant for the default case at least. This Flutter theming limitation and impact is thus now the same in FCS, as it is with vanilla Flutter ThemeData and its CardTheme. It is still broken as mentioned in the above issue, but that is a Flutter theming issue and limitation that FCS cannot fix.

• Changed the FlexSubThemes.inputDecoratorTheme to use only border and its WidgetState for its theme. It offers more and nicer control over hover state than using the older legacy more limited border styles.

FIX

• Fixed #​198 AppBar color issue when using seed generated scheme with key color locked.

• Fixed that the Rectangular Slider value indicator did not default to primary color when undefined, as intended in FCS M2 and M3 mode. Only the Drop style indicator defaulted to primary. This came from the framework defaulting the old M2 rectangular indicator to a complex, opacity and alpha blended onSurface grey looking result.

Why is blendedTextTheme deprecated?

The blendTextTheme feature was originally made before Material-3's TextTheme was available, before it was fully known how it was going to be implemented. It was an approximation of the TextStyles that could be seen in early versions of Material-3 images. Since the actual Material-3 TextTheme is available, the tinted TextTheme feature is no longer required. While the FCS tinted TextTheme did provide an alternative version of the actual tint used in Material-3, the differences were quite subtle. Additionally, recent changes in Flutter make using it very verbose and complicated. Why it does so is explained in detail below.

In Material-3 Typography 2021, the TextTheme and all styles in it are fully opaque and use onSurface as color on all TextStyles. In a seed generated ColorScheme, the text styles become primary color tinted, because the onSurface color by default has subtle primary tint. With FCS, you can modify the onSurface to black or white to avoid this, if so preferred.

In Material-2 Typography 2018 and 2014, some TextStyles in their TextThemes use partially transparent white or black colors, making them appear tinted when placed on lightly colored backgrounds. Such TextStyles also have lower contrast. If the Material-3 default text theme is used on background colors that are tinted with a color that deviates a lot in hue from the hue used as tint color by the TextTheme, it may not fit it so well. The Material-2 opacity-based text styles do not have this limitation. It is unknown why Material-3 switched to a fixed tint color instead of using the opacity-based approach used in Material-2, that is more universally usable on backgrounds with different tint colors.

In Material-3, some component themes override the default color of the default TextTheme TextStyles they use with onSurfaceVariant. This color has slightly more tint and lower contrast than the default onSurface. This is used for elements in components that should have less emphasis. Many default Material-3 components also override the color in default TextTheme TextStyles they use with ColorScheme.onSurface color, that it actually already has in a default TextTheme. These two overrides results in that whatever color the default TextTheme TextStyles have, they will be overridden by these ColorScheme colors. Resulting in that any custom-colored TextThemeand its TextStyles are not getting used by such Material-3 components and that the custom colors from the meticulously colored custom TextTheme, are rarely visible anywhere in a Material-3 application. Material-2 component themes do not do this, nor did older Flutter versions of Material-3 component themes do this.

An issue has been raised explaining the challenges this newer approach in Flutter causes when using custom colored text themes. If this issue is addressed, the tinted TextTheme feature in FCS may be brought back if it is a requested feature.

In current Flutter versions, using a custom-tinted TextTheme is rather pointless. You can, but it is not enough to define the TextTheme. You also have to pass each tinted TextStyle it has to the appropriate TextStyles in ALL component themes that override its colors, for it to have any effect. It is typically not worth the effort.

THEMES PLAYGROUND

NEW

• The Theme Code view panel now has a toggle that allows you to generate the configured code for the theme as input suitable for a separate app theme file. It has static getters that you can use in your MaterialApp's theme and darkTheme.

  TIP: You can modify this file and e.g., pass in controller that contains user-configurable settings for theme configuration properties and generate the theme on the fly in your app. This way you can let the user configure the theme in your app, a few props anyway. This is basically what the Playground app does with all theming properties. That is why you can see the result and impact of defined theme in the Playground app itself, as you modify the desired theme configuration in the app.

• The Theme Code view got a long asked for feature, Themes Playground settings export and import! You can now export your configured theme settings to a JSON file and import them back into the Playground later. This is a great way to save your theme settings for later use or to share them with others. The exported JSON file contains all the internal controller settings values you have configured in the Playground that are needed to restore a given configuration state. This Playground feature was contributed by GitHub user @​akiller in !PR 257. Thank you!

• The contributed feature got enhanced with more error handling and a slightly refined UI to make it production ready.

• As a further enhancement of the JSON export feature, the Themes Playground app also got the ability to convert the exported settings JSON config to a shareable URL. You can now share Playground settings with other Flutter developers.

• On each theme settings panel, many controls now appear in two columns to reduce the need to scroll so much on wider media and see more controls on the same screen. The layout is panel width responsive and controls will be in one column as before on smaller media.

• Split the "FAB and Chip" settings panels to separate panels FAB and Chip.

• Split the "BottomAppBar and SearchBar" panels to separate panels SearchBar and BottomAppBar.

• On the surface Color Blends settings panel, you can choose which surface color the scaffold background color will use as its starting point surface color and as base for the blend level and mode. You can also select any ColorScheme color and use it as an override for the scaffold background color. This will override any blended color result as well as the plain white and true black settings.

• The ColorScheme settings panel got five new settings:

  1. Contrast level slider control for MCU based scheme variants. This feature is equivalent to the FSS based scheme variant contrast level control. It is als available in the Flutter master channel as contrastLevel property in ColorScheme.fromSeed. It is used to control the contrast level of the generated scheme colors. It will most likely land in the next stable Flutter release after 3.24. With FCS V8 you can use it already now.
  2. A dropdown for Fixed colors, where you can choose between three different variants for the fixed, onFixed, fixedDim and onFixedVariant colors, when a seed generated ColorScheme is NOT being used.
  3. A Switch for Higher contrast fixed and fixedDim colors. When using FSS based seed generated color schemes, you can keep the standard Material-3 based tones for the fixed, onFixed, fixedDim and onFixedVariant colors to the Material-3 design specified values 90, 10, 80, 30 or and or opt-in on an alternative set 92, 6, 84, 12 that have higher contrast.
  4. A Switch for Expressive LIGHT containers. The Material design spec for the tones used by the colors onPrimaryContainer, onSecondaryContainer, onTertiaryContainer and onErrorContainer have changed from tone 10 to 30 for LIGHT theme mode. This change will land in Flutter when the Material Color Utilities (MCU) package is updated to at least 0.12.0. This has not been done even in master (Sep 3, 2024).
     • A toggle was added where you can opt in on using them already now in FCS. It is not ON by default. When it lands in stable Flutter, it will be made ON by default, but you will still be able to opt out of using it. Flutter SDK and MCU will not contain such an opt-out feature. The new on colors for containers in light mode, make them more color expressive, but it also reduces their contrast level and accessibility. We prefer them to have higher contrast.
  5. A switch for using **Legacy monochrome seed